home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / spiele / workbench spiele / krsnake / src / autodocs / krsnake.doc < prev    next >
Text File  |  1995-10-26  |  16KB  |  468 lines
  1. TABLE OF CONTENTS
  2.  
  3. krsnake.library/---overview---
  4. krsnake.library/KsDeleteSoundObject
  5. krsnake.library/KsGetClientSig
  6. krsnake.library/KsNotifyServer
  7. krsnake.library/KsPlaySoundObject
  8. krsnake.library/KsReadEvent
  9. krsnake.library/KsReadKRSNAkePrefs
  10. krsnake.library/KsReadSoundObject
  11. krsnake.library/KsRegisterClient
  12. krsnake.library/KsRemoveClient
  13. krsnake.library/KsWaitForEvent
  14. krsnake.library/KsWriteKRSNAkePrefs
  15.  
  16. krsnake.library/---overview---             krsnake.library/---overview---
  17.  
  18.    WRITING KRSNAKE CLIENTS
  19.  
  20.         KRSNAke clients need to communicate with the main program. This is
  21.         done through krsnake.library. A client would call
  22.         KsRegisterClient() in order to receive messages from KRSNAke, wait
  23.         around for the client's signal to arrive, act upon the received
  24.         message, repeat that until a SNAKE_QUIT message arrives, then call
  25.         KsRemoveClient(). There's nothing more to it.
  26.  
  27.         A KRSNAke client might look like this:
  28.  
  29.             client = KsRegisterClient();
  30.                 ...
  31.                 KsWaitForEvent(client);
  32.                 KsReadEvent(client,&event,&data);
  33.                 ...
  34.             KsRemoveClient(client);
  35.  
  36.         Although more commonly you'd want to listen to other ports as
  37.         well, for instance that of a window:
  38.  
  39.             client = KsRegisterClient();
  40.                 ...
  41.                 mask = (1<<KsGetClientSig(client))|(1<<windowsigbit);
  42.                 Wait(mask);
  43.                 KsReadEvent(client,&event,&data);
  44.                 ...
  45.             KsRemoveClient(client);
  46.  
  47.         If you experience difficulties following my explanation (which I
  48.         suppose is entirely possible), try looking at the sources of the
  49.         clients I've written. Sources speak more eloquently than words. If
  50.         you don't read E - tough luck, you're stuck with my explanation.
  51.  
  52.    NOTE ABOUT THE INTERFACE
  53.  
  54.         Clients should never open any interface window, or generally give
  55.         off any clue whatsoever that they exist, until told to do so by
  56.         KRSNAke. Clients should do general initialisation, attach them-
  57.         selves to KRSNAke, then wait around for a SNAKE_SHOWINTERFACE event
  58.         to be broadcast. At THIS point, they should render. Of course,
  59.         when dealing with particularly weird users, this could never
  60.         happen. Be prepared for everything.
  61.  
  62.    EVENT CODES
  63.  
  64.         KRSNAke broadcasts the following event codes (with data codes in
  65.         parentheses):
  66.  
  67.            SNAKE_QUIT (no data)
  68.  
  69.                 If your client receives SNAKE_QUIT, remove it as soon as
  70.                 possible. This means KRSNAke is trying to quit - and it
  71.                 can't until you've removed your client. Generally, this
  72.                 message doesn't just mean "call KsRemoveClient()", it
  73.                 means "quit your program".
  74.  
  75.            SNAKE_NEWSCORE (current score)
  76.  
  77.                 This message is broadcast whenever the score (the length
  78.                 of the snake) changes.
  79.  
  80.            SNAKE_GAMEOVER (final score)
  81.  
  82.                 When the snake crashes, SNAKE_GAMEOVER is broadcast, along
  83.                 with the snake's final length.
  84.  
  85.            SNAKE_NEWGAME (no data)
  86.  
  87.                 This message is broadcast when the player begins a new
  88.                 game.
  89.  
  90.            SNAKE_PAUSED (no data)
  91.  
  92.                 This message is broadcast when the game is paused.
  93.  
  94.            SNAKE_RESTARTED (no data)
  95.  
  96.                 This message is broadcast when the game is resumed after a
  97.                 pause.
  98.  
  99.            SNAKE_EATEN (fruit's value)
  100.  
  101.                 When the snake eats a fruit, this code is broadcast along
  102.                 with the fruit's value.
  103.  
  104.            SNAKE_MOVES (head graphic, head's coordinates)
  105.  
  106.                 Each time the snake's position changes (its head moves),
  107.                 this message is broadcast along with the new coordinates
  108.                 of the head. The coordinates are broadcast as a word,
  109.                 where the most significant byte is the Y coordinate
  110.                 (between 0 and 31), and the least significant byte is the
  111.                 X coordinate (also between 0 and 31). Preceding this word
  112.                 is a byte containing the head graphic that was rendered
  113.                 (even if graphics are currently not used, in which case it
  114.                 would be the head that WOULD have been rendered). This
  115.                 provides direction information.
  116.  
  117.            SNAKE_NEWCHUNK (fruit data; see below)
  118.  
  119.                 Whenever a new fruit arrives (either at the start of the
  120.                 game, or when the snake eats a fruit), this message is
  121.                 broadcast along with all info about the new fruit. The
  122.                 data is coded as a longword, each value represented as a
  123.                 byte as follows, most significant byte first: fruit value
  124.                 (between 1 and 9), fruit colour (between 0 and 3; RGB
  125.                 values can be obtained from KRSNAke's prefs file), fruit Y
  126.                 coordinate (between 0 and 31), and fruit X coordinate
  127.                 (between 0 and 31).
  128.  
  129.            SNAKE_SHOWINTERFACE (no data)
  130.  
  131.                 When this message is broadcast, the client should open its
  132.                 window. If the window is already open, do nothing - but
  133.                 make sure you handle the message, because these messages
  134.                 are sent occasionally just to be sure the client really
  135.                 did get the message.
  136.  
  137.            SNAKE_HIDEINTERFACE (no data)
  138.  
  139.                 When this message is broadcast, the client should close
  140.                 its window and anything similar. The same applies here as
  141.                 to SNAKE_SHOWINTERFACE - duplicate messages do occur!
  142.                 It's generally unwanted that your client creates an AppIcon
  143.                 or something similar for itself when it's hidden - all
  144.                 show/hide info should come from KRSNAke.
  145.  
  146.    NOTE
  147.  
  148.         Generally, it's a bad idea to call any of the server functions
  149.         from your own code. Only KRSNAke should do this; at any one time,
  150.         there can be only one server in existence, and this server should
  151.         be owned by KRSNAke's main task. This library is not intended as
  152.         a multipurpose client/server library - it's only for KRSNAke.
  153.  
  154.         In fact, I've removed the docs for the server functions below.
  155.         Just be a nice fellow and don't call them, OK?
  156.  
  157.         YOU HAVE BEEN WARNED!
  158.  
  159.             "We hear what you say,
  160.              we see what you do;
  161.              we know everything we need to know about you."
  162.  
  163. krsnake.library/KsDeleteSoundObject   krsnake.library/KsDeleteSoundObject
  164.  
  165.    NAME
  166.         KsDeleteSoundObject -- delete a sound object
  167.  
  168.    SYNOPSIS
  169.         KsDeleteSoundObject(object)
  170.                             D0
  171.  
  172.         void KsDeleteSoundObject(APTR);
  173.  
  174.    FUNCTION
  175.         Deletes a sound object created with KsReadSoundObject().
  176.  
  177.    INPUTS
  178.         object - pointer to an object returned from KsReadSoundObject()
  179.  
  180.    SEE ALSO
  181.         KsPlaySoundObject(), KsReadSoundObject()
  182.  
  183. krsnake.library/KsGetClientSig             krsnake.library/KsGetClientSig
  184.  
  185.    NAME
  186.         KsGetClientSig -- get the signal of a client port
  187.  
  188.    SYNOPSIS
  189.         signal = KsGetClientSig(client)
  190.         D0                      D0
  191.  
  192.         UBYTE KsGetClientSig(APTR);
  193.  
  194.    FUNCTION
  195.         This function returns the signal that will be set when a message
  196.         arrives at the given client's message port. Using a Wait() for
  197.         this signal is somewhat more useful than using KsWaitForEvent(),
  198.         as this will let you listen to other signals as well.
  199.  
  200.    INPUTS
  201.         client - a pointer to the client whose signal you wish to obtain.
  202.  
  203.    RESULT
  204.         signal - the number of the signal associated with the given
  205.                  client's port.
  206.  
  207.    SEE ALSO
  208.         KsReadEvent(), KsWaitForEvent()
  209.  
  210. krsnake.library/KsNotifyServer             krsnake.library/KsNotifyServer
  211.  
  212.    NAME
  213.         KsNotifyServer -- notify the server about an event
  214.  
  215.    SYNOPSIS
  216.         success = KsNotifyServer(event,data)
  217.         D0                       A0    D0
  218.  
  219.         ULONG KsNotifyServer(ULONG,ULONG);
  220.  
  221.    FUNCTION
  222.         Notifies the KRSNAke server about a particular event. At present,
  223.         only the SNAKE_NEWPREFS event (with no parameters) is recognised.
  224.         This event will cause KRSNAke to restart itself (and to restart
  225.         all clients).
  226.  
  227.    INPUTS
  228.         event - the event to broadcast
  229.         data - the data (if any) for the event
  230.  
  231.    RESULT
  232.         success - TRUE if the event was broadcast to the server, FALSE
  233.                   otherwise
  234.  
  235.    SEE ALSO
  236.  
  237. krsnake.library/KsPlaySoundObject       krsnake.library/KsPlaySoundObject
  238.  
  239.    NAME
  240.         KsPlaySoundObject -- trigger a sound object
  241.  
  242.    SYNOPSIS
  243.         success = KsPlaySoundObject(object)
  244.         D0                          D0
  245.  
  246.         ULONG KsPlaySoundObject(APTR);
  247.  
  248.    FUNCTION
  249.         Starts playing a sound object created with KsReadSoundObject(),
  250.         either by triggering the sound.datatype or by starting the
  251.         respective replayer. Note that only datatypes can be played more
  252.         than one at a time. Also, beware of the ProTracker replayer, which
  253.         is not working at present.
  254.  
  255.    INPUTS
  256.         object - pointer to a sound object returned from
  257.                  KsReadSoundObject()
  258.  
  259.    RESULT
  260.         success - TRUE if the object was successfully triggered, FALSE
  261.                   otherwise
  262.  
  263.    SEE ALSO
  264.         KsDeleteSoundObject(), KsReadSoundObject()
  265.  
  266. krsnake.library/KsReadEvent                   krsnake.library/KsReadEvent
  267.  
  268.    NAME
  269.         KsReadEvent -- receive a message from the server
  270.  
  271.    SYNOPSIS
  272.         success = KsReadEvent(client,event,data)
  273.         D0                    A0     D1    D0
  274.  
  275.         ULONG KsReadEvent(APTR,ULONG *,ULONG *);
  276.  
  277.    FUNCTION
  278.         This function reads a message from the client's message port. If a
  279.         message exists, it will copy the event and data codes into the
  280.         addresses provided by the caller, and dispose of the message.
  281.  
  282.         You should keep calling this function until it returns FALSE, as
  283.         several messages might arrive at the port simultaneously.
  284.  
  285.    INPUTS
  286.         client - the client whose port to check.
  287.         event - pointer to a longword in which to store the event code of
  288.                 the message, if there is one.
  289.         data - ditto for the data code.
  290.  
  291.    RESULT
  292.         success - TRUE if there was a message, in which case the longwords
  293.                   pointed to by the event and data fields will contain the
  294.                   info broadcast by the message, FALSE if there was no
  295.                   message.
  296.  
  297.    SEE ALSO
  298.  
  299. krsnake.library/KsReadKRSNAkePrefs     krsnake.library/KsReadKRSNAkePrefs
  300.  
  301.     NAME
  302.          KsReadKRSNAkePrefs -- read the user preferences
  303.  
  304.     SYNOPSIS
  305.          prefs = KsReadKRSNAkePrefs()
  306.          D0
  307.  
  308.          struct KPrefs * KsReadKRSNAkePrefs(void);
  309.  
  310.     FUNCTION
  311.          Reads the file "ENVARC:KRSNAke/KRSNAke.prefs" and creates a
  312.          KPrefs structure out of it. This structure is allocated with
  313.          AllocVec(), so when you're done with it, call FreeVec(). If
  314.          you've changed anything and want to make it permanent, call
  315.          KsWriteKRSNAkePrefs() rather than FreeVec().
  316.  
  317.     RESULT
  318.          prefs - a pointer to an allocated KPrefs structure. Unless you
  319.                  are the KRSNAke prefs program, you should consider this
  320.                  structure read only! If no prefs could be found, or if
  321.                  there was no memory to read them, the function returns
  322.                  NULL.
  323.  
  324.     SEE ALSO
  325.          KsWriteKRSNAkePrefs()
  326.  
  327. krsnake.library/KsReadSoundObject       krsnake.library/KsReadSoundObject
  328.  
  329.    NAME
  330.         KsReadSoundObject -- create a sound object
  331.  
  332.    SYNOPSIS
  333.         object = KsReadSoundObject(filename)
  334.         D0                         D0
  335.  
  336.         APTR KsReadSoundObject(char *);
  337.  
  338.    FUNCTION
  339.         This function reads a file from a filesystem, and if the file is
  340.         a recognised sound data file, a sound object, which can
  341.         subsequently be played, is created.
  342.  
  343.    INPUTS
  344.         filename - a pointer to the name of the file to attempt to load
  345.  
  346.    RESULT
  347.         object - a sound object which can be played with KsPlaySoundObject,
  348.                  or NULL if something went wrong
  349.  
  350.    SEE ALSO
  351.         KsDeleteSoundObject(), KsReadSoundObject()
  352.  
  353. krsnake.library/KsRegisterClient         krsnake.library/KsRegisterClient
  354.  
  355.    NAME
  356.         KsRegisterClient -- create a KRSNAke message client
  357.  
  358.    SYNOPSIS
  359.         client = KsRegisterClient()
  360.         D0
  361.  
  362.         APTR KsRegisterClient(void);
  363.  
  364.    FUNCTION
  365.         This function creates a client of the KRSNAke message server. A
  366.         KRSNAke client should call this in order to receive messages from
  367.         KRSNAke through the KsReadEvent() call.
  368.  
  369.         The message server must be active before any clients can be
  370.         created. If it is not, this function will fail. Normally, clients
  371.         will be launched by KRSNAke after the server has been created, so
  372.         this should not be a problem.
  373.  
  374.    RESULT
  375.         client - a pointer to a KRSNAke message client structure, or FALSE
  376.                  if the client could not be created.
  377.  
  378.    SEE ALSO
  379.         KsRemoveClient(), KsReadEvent()
  380.  
  381. krsnake.library/KsRemoveClient             krsnake.library/KsRemoveClient
  382.  
  383.    NAME
  384.         KsRemoveClient -- destroy a KRSNAke message client
  385.  
  386.    SYNOPSIS
  387.         success = KsRemoveClient(client)
  388.         D0                       D0
  389.  
  390.         ULONG KsRemoveClient(APTR);
  391.  
  392.    FUNCTION
  393.         This function detaches a client from the server and destroys it.
  394.         All clients created by the KsRegisterClient() function must be
  395.         disposed of with this function.
  396.  
  397.    INPUTS
  398.         client - a pointer to a client returned from the
  399.                  KsRegisterClient() function.
  400.  
  401.    RESULT
  402.         success - TRUE if the client was removed, FALSE otherwise.
  403.  
  404.    SEE ALSO
  405.         KsRegisterClient()
  406.  
  407. krsnake.library/KsWaitForEvent             krsnake.library/KsWaitForEvent
  408.  
  409.    NAME
  410.         KsWaitForEvent -- wait for a message to arrive at a client's port
  411.  
  412.    SYNOPSIS
  413.         success = KsWaitForEvent(client)
  414.         D0                       D0
  415.  
  416.         ULONG KsWaitForEvent(APTR);
  417.  
  418.    FUNCTION
  419.         This function calls WaitPort() for the given client's port, which
  420.         causes the calling task to wait until the client receives a
  421.         message from the server.
  422.  
  423.    INPUTS
  424.         client - the client whose port to wait on.
  425.  
  426.    RESULT
  427.         success - TRUE if the wait succeeded, FALSE otherwise. At present,
  428.                   the FALSE return value only happens if you pass a NULL
  429.                   client pointer.
  430.  
  431.    SEE ALSO
  432.         KsGetClientSig(), KsReadEvent()
  433.  
  434. krsnake.library/KsWriteKRSNAkePrefs   krsnake.library/KsWriteKRSNAkePrefs
  435.  
  436.     NAME
  437.          KsWriteKRSNAkePrefs -- write the user preferences
  438.  
  439.     SYNOPSIS
  440.          success = KsWriteKRSNAkePrefs(prefs)
  441.          D0                            D0
  442.  
  443.          ULONG KsWriteKRSNAkePrefs(struct KPrefs *);
  444.  
  445.     FUNCTION
  446.          Writes the KPrefs structure passed as the file
  447.          "ENVARC:KRSNAke/KRSNAke.prefs" and deallocates it.
  448.  
  449.          If you just want to deallocate it, call FreeVec(prefs),
  450.          NOT KsWriteKRSNAkePrefs(prefs)! This function is only
  451.          meant for changes you want to be permanent - ie. if you're
  452.          the prefs program or something similar.
  453.  
  454.     INPUTS
  455.          prefs - pointer to a KPrefs structure.
  456.  
  457.     RESULT
  458.          success - TRUE if the operation succeeded, FALSE otherwise.
  459.                    Note that if this function fails, the structure is
  460.                    not deallocated. This is generally bad, but there's
  461.                    nothing the library will do about it, so you should
  462.                    FreeVec() it yourself.
  463.  
  464.     SEE ALSO
  465.          KsReadKRSNAkePrefs()
  466.  
  467.  
  468.